Error Handling

Error Response Format

All SuperDoc API errors follow a consistent JSON structure:

{
  "code": "ERROR_CODE",
  "error": "Error Type",
  "message": "Human-readable error description",
  "requestId": "req_abc123",
  "timestamp": "2024-01-15T10:30:00Z"
}

string

required

Machine-readable error code for programmatic handling

string

required

HTTP status text (e.g., “Bad Request”, “Unauthorized”)

string

required

Human-readable error description

string

required

Unique identifier for the request (useful for support)

string

ISO 8601 timestamp when the error occurred

HTTP Status Codes

SuperDoc API uses standard HTTP status codes:

400 Bad Request

Client Error - Invalid request format or parametersCommon causes:

Missing required parameters
Invalid file format
Malformed request body
File too large

401 Unauthorized

Authentication Error - Invalid or missing API key Common causes: - Missing Authorization header - Invalid API key format - Expired or revoked API key

403 Forbidden

Authorization Error - Valid credentials but insufficient permissions Common causes: - Plan limitations exceeded - Feature not available in current plan - IP address restrictions

429 Too Many Requests

Rate Limiting - Request quota exceeded Common causes: - Hourly rate limit exceeded - Daily rate limit exceeded - Burst limit exceeded

500 Internal Server Error

Server Error - Unexpected server-side issue Common causes: - Temporary service disruption - Document processing failure - Resource exhaustion

503 Service Unavailable

Service Unavailable - Temporary service interruptionCommon causes:

Scheduled maintenance
System overload
Dependency failures

Common Error Codes

Authentication Errors

{
  "code": "MISSING_AUTH",
  "error": "Unauthorized",
  "message": "Authorization header is required",
  "requestId": "req_abc123"
}

{
  "code": "INVALID_API_KEY",
  "error": "Unauthorized",
  "message": "The provided API key is invalid or has been revoked",
  "requestId": "req_def456"
}

{
  "code": "EXPIRED_API_KEY",
  "error": "Unauthorized",
  "message": "The API key has expired. Please generate a new one",
  "requestId": "req_ghi789"
}

File Processing Errors

{
  "code": "INVALID_FILE_TYPE",
  "error": "Bad Request",
  "message": "Only DOCX files are supported for conversion",
  "requestId": "req_jkl012"
}

{
  "code": "FILE_TOO_LARGE",
  "error": "Bad Request",
  "message": "File size exceeds the 25MB limit",
  "requestId": "req_mno345"
}

{
  "code": "CORRUPTED_FILE",
  "error": "Bad Request",
  "message": "The uploaded file appears to be corrupted and cannot be processed",
  "requestId": "req_pqr678"
}

{
  "code": "CONVERSION_FAILED",
  "error": "Internal Server Error",
  "message": "Document conversion failed due to processing error",
  "requestId": "req_stu901"
}

Rate Limiting Errors

{
  "code": "RATE_LIMIT_EXCEEDED",
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 3600 seconds",
  "requestId": "req_vwx234",
  "retryAfter": 3600
}

{
  "code": "QUOTA_EXCEEDED",
  "error": "Forbidden",
  "message": "Monthly quota exceeded. Upgrade your plan or wait for reset",
  "requestId": "req_yzab567"
}

Error Handling Strategies

Basic Error Handling

async function convertDocument(file) {
  try {
    const response = await fetch('/v1/convert?format=pdf', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
      },
      body: formData
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.code} - ${error.message}`);
    }

    return await response.blob();

} catch (error) {
console.error('Conversion failed:', error.message);
throw error;
}
}

import requests
from requests.exceptions import RequestException

def convert_document(file_path, api_key):
    try:
        with open(file_path, 'rb') as f:
            files = {'file': f}
            headers = {'Authorization': f'Bearer {api_key}'}

            response = requests.post(
                'https://api.superdoc.dev/v1/convert?format=pdf',
                headers=headers,
                files=files
            )

        if response.status_code != 200:
            error_data = response.json()
            raise Exception(f"API Error: {error_data['code']} - {error_data['message']}")

        return response.content

    except RequestException as e:
        print(f"Request failed: {e}")
        raise
    except Exception as e:
        print(f"Conversion failed: {e}")
        raise

<?php
function convertDocument($filePath, $apiKey) {
    $curl = curl_init();

    curl_setopt_array($curl, [
        CURLOPT_URL => 'https://api.superdoc.dev/v1/convert?format=pdf',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey
        ],
        CURLOPT_POSTFIELDS => [
            'file' => new CURLFile($filePath)
        ]
    ]);

    $response = curl_exec($curl);
    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);

    if ($httpCode !== 200) {
        $error = json_decode($response, true);
        throw new Exception("API Error: {$error['code']} - {$error['message']}");
    }

    return $response;
}
?>

Advanced Error Handling with Retry Logic

class SuperDocClient {
  constructor(apiKey, maxRetries = 3) {
    this.apiKey = apiKey;
    this.maxRetries = maxRetries;
  }

async convertWithRetry(file) {
for (let attempt = 0; attempt < this.maxRetries; attempt++) {
try {
return await this.convert(file);
} catch (error) {
if (this.shouldRetry(error, attempt)) {
const delay = this.calculateDelay(attempt);
await this.sleep(delay);
continue;
}
throw error;
}
}
}

shouldRetry(error, attempt) {
if (attempt >= this.maxRetries - 1) return false;

    // Retry on server errors and rate limits
    return error.status >= 500 || error.status === 429;

}

calculateDelay(attempt) {
// Exponential backoff with jitter
const baseDelay = Math.pow(2, attempt) _ 1000;
const jitter = Math.random() _ 1000;
return baseDelay + jitter;
}

sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
}

import time
import random
from enum import Enum

class CircuitState(Enum):
    CLOSED = 1
    OPEN = 2
    HALF_OPEN = 3

class CircuitBreaker:
    def __init__(self, failure_threshold=5, recovery_timeout=60):
        self.failure_threshold = failure_threshold
        self.recovery_timeout = recovery_timeout
        self.failure_count = 0
        self.last_failure_time = None
        self.state = CircuitState.CLOSED

    def call(self, func, *args, **kwargs):
        if self.state == CircuitState.OPEN:
            if time.time() - self.last_failure_time > self.recovery_timeout:
                self.state = CircuitState.HALF_OPEN
            else:
                raise Exception("Circuit breaker is OPEN")

        try:
            result = func(*args, **kwargs)
            self.on_success()
            return result
        except Exception as e:
            self.on_failure()
            raise

    def on_success(self):
        self.failure_count = 0
        self.state = CircuitState.CLOSED

    def on_failure(self):
        self.failure_count += 1
        self.last_failure_time = time.time()

        if self.failure_count >= self.failure_threshold:
            self.state = CircuitState.OPEN

Error Handling Best Practices

Use specific error handling

Handle different error types with appropriate responses:

function handleApiError(error) {
  switch (error.code) {
    case 'RATE_LIMIT_EXCEEDED':
      return scheduleRetry(error.retryAfter);
    case 'FILE_TOO_LARGE':
      return showFileSizeError();
    case 'INVALID_FILE_TYPE':
      return showFileTypeError();
    case 'INVALID_API_KEY':
      return redirectToAuth();
    default:
      return showGenericError();
  }
}

Log errors for debugging

Always log errors with context:

function logError(error, context) {
  console.error('SuperDoc API Error:', {
    code: error.code,
    message: error.message,
    requestId: error.requestId,
    timestamp: error.timestamp,
    context: context
  });
}

Provide user-friendly messages

Translate technical errors into user-friendly messages:

const ERROR_MESSAGES = {
  'INVALID_FILE_TYPE': 'Please select a valid Word document (.docx file)',
  'FILE_TOO_LARGE': 'File size must be less than 25MB',
  'RATE_LIMIT_EXCEEDED': 'Too many requests. Please try again later',
  'CONVERSION_FAILED': 'Unable to convert document. Please try again'
};

Implement graceful degradation

Provide alternatives when the API is unavailable:

async function convertWithFallback(file) {
  try {
    return await superDocConvert(file);
  } catch (error) {
    if (error.status >= 500) {
      // Fallback to alternative service or queue for later
      return fallbackConverter(file);
    }
    throw error;
  }
}

Monitoring and Alerting

Error Rate Monitoring

Track error rates to identify issues:

class ErrorTracker {
  constructor() {
    this.errors = new Map();
    this.window = 60000; // 1 minute
  }

  recordError(errorCode) {
    const now = Date.now();
    const windowStart = now - this.window;

    if (!this.errors.has(errorCode)) {
      this.errors.set(errorCode, []);
    }

    const timestamps = this.errors.get(errorCode);
    timestamps.push(now);

    // Remove old timestamps
    this.errors.set(
      errorCode,
      timestamps.filter((t) => t > windowStart)
    );
  }

  getErrorRate(errorCode) {
    const timestamps = this.errors.get(errorCode) || [];
    return timestamps.length;
  }
}

Health Check Implementation

async function healthCheck() {
  try {
    const response = await fetch("https://api.superdoc.dev/v1/health");
    return response.ok;
  } catch (error) {
    return false;
  }
}

// Monitor API health
setInterval(async () => {
  const isHealthy = await healthCheck();
  if (!isHealthy) {
    console.warn("SuperDoc API appears to be down");
    // Trigger alerts or fallback behavior
  }
}, 30000); // Check every 30 seconds

Getting Help

When encountering persistent errors:

Check Status Page

Monitor service status and planned maintenance

Contact Support

Include the requestId for faster troubleshooting

Always include the requestId from error responses when contacting support. This helps us quickly locate and diagnose the specific request.

Getting Started

Core Concepts

Error Response Format

HTTP Status Codes

Common Error Codes

Authentication Errors

File Processing Errors

Rate Limiting Errors

Error Handling Strategies

Basic Error Handling

Advanced Error Handling with Retry Logic

Error Handling Best Practices

Monitoring and Alerting

Error Rate Monitoring

Health Check Implementation

Getting Help

Check Status Page

Contact Support

​Error Response Format

​HTTP Status Codes

​Common Error Codes

​Authentication Errors

​File Processing Errors

​Rate Limiting Errors

​Error Handling Strategies

​Basic Error Handling

​Advanced Error Handling with Retry Logic

​Error Handling Best Practices

​Monitoring and Alerting

​Error Rate Monitoring

​Health Check Implementation

​Getting Help

Check Status Page

Contact Support

Error Response Format

HTTP Status Codes

Common Error Codes

Authentication Errors

File Processing Errors

Rate Limiting Errors

Error Handling Strategies

Basic Error Handling

Advanced Error Handling with Retry Logic

Error Handling Best Practices

Monitoring and Alerting

Error Rate Monitoring

Health Check Implementation

Getting Help